Asynchronous Notification

Overview

When a merchant payment to a bank card has a result, PayBy sends the related result to the merchant.

The merchant needs to receive and process the notification, then return a response. The actual arrival time depends on the settlement time of each bank and is subject to the actual arrival time.

Notification Handling Guidelines

1. Duplicate Notifications
   PayBy may send the same notification multiple times. The merchant system must be capable of identifying and handling duplicate notifications correctly to avoid processing the same transaction more than once.

2. Notification Retry Mechanism
   If PayBy receives an invalid response or no response (timeout) from the merchant system during backend notification, it will consider the attempt failed and retry the notification.

   • Retry Policy: Up to 7 attempts
   • Retry Intervals: 2, 10, 10, 60, 120, 360, and 900 minutes
     Please note: PayBy does not guarantee final delivery success.

3. Unclear Order Status
   If the payment result is not received or the order status is unclear, merchants are advised to actively query the order status using the transfer query interface.

4. Signature Verification
   All notification requests are signed using PayBy’s RSA private key.

   • The signature algorithm is the same as for ordinary requests.
   • Merchants must verify the signature using PayBy’s public key, which can be downloaded from the merchant portal.

Notification Parameters

The notification request format is the same as ordinary requests, using the HTTP protocol with HTTP headers and a JSON object in the HTTP body.

Field Name	Variable Name	Required	Type	Example	Description
Bank Card Transfer Order Information	transferBankCardOrder	Required	TransferBankCardOrder	-	Contains the details of the bank card transfer order

Attributes

TransferBankCardOrder

---

• Request Time (requestTime)

  • Required: Yes
  • Type: Timestamp(3)
  • Example: 1581493898000
  • Description: —

• Merchant Order Number (merchantOrderNo)

  • Required: Yes
  • Type: String(64)
  • Example: S10000
  • Description: —

• PayBy Order Number (orderNo)

  • Required: Yes
  • Type: String(32)
  • Example: O1000
  • Description: —

• Product Name (product)

  • Required: Yes
  • Type: String(200)
  • Example: Transfer Bank Card
  • Description: —

• Order Status (status)

  • Required: Yes
  • Type: —
  • Example: -
  • Description: —

• Amount (amount)

  • Required: Yes
  • Type: Money
  • Example: —
  • Description: —

• Account Holder Type (accountHolderType)

  • Required: Yes
  • Type: String(16)
  • Example: INDIVIDUAL
  • Description: INDIVIDUAL or CORPORATE

• First Name (firstName)

  • Required: Optional
  • Type: String(200)
  • Example: —
  • Description: SHA256 of original text, required if INDIVIDUAL

• Last Name (lastName)

  • Required: Optional
  • Type: String(200)
  • Example: —
  • Description: SHA256 of original text, required if INDIVIDUAL

• Middle Name (middleName)

  • Required: Optional
  • Type: String(200)
  • Example: —
  • Description: SHA256 of original text

• Company Name (companyName)

  • Required: Optional
  • Type: String(200)
  • Example: —
  • Description: SHA256 of original text, required if CORPORATE

• Card Number (cardNumber)

  • Required: Yes
  • Type: String(64)
  • Example: —
  • Description: SHA256 of original text

• Expiry Month (expiryMonth)

  • Required: Yes
  • Type: String(2)
  • Example: —
  • Description: —

• Expiry Year (expiryYear)

  • Required: Yes
  • Type: String(4)
  • Example: —
  • Description: —

• Payment Memo (memo)

  • Required: Optional
  • Type: String(128)
  • Example: —
  • Description: —

• Notification URL (notifyUrl)

  • Required: Optional
  • Type: String(200)
  • Example: —
  • Description: —

• Failure Description (failDes)

  • Required: Optional
  • Type: String(200)
  • Example: -
  • Description: Reason for order failure

• Bank Reference Number (bankReference)

  • Required: Optional
  • Type: String(128)
  • Example: —
  • Description: —

• Payer Fee Amount (payerFeeAmount)

  • Required: Yes
  • Type: Money
  • Example: -
  • Description: —

• Fee Payer ID (payerFeeMemberId)

  • Required: Yes
  • Type: String(32)
  • Example: -
  • Description: ID of the party paying the fee

• Payment Time (paidTime)

  • Required: Yes
  • Type: Date
  • Example: -
  • Description: Time of deduction

• Refund Time (refundedTime)

  • Required: Optional
  • Type: Date
  • Example: —
  • Description: Time of refund

---

Notification Sample

{
  "transferBankCardOrder": {
    // Transfer bank card order details will be provided here
  }
}

Response Parameters

After the merchant receives the notification, return "SUCCESS" to indicate successful receipt.

Any other response indicates an exception.

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success	-
400	INVALID_PARAMETER	Parameter error	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too early compared to current time	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too late compared to current time	Adjust request time
402	RATE_LIMIT_REJECT	Request too frequent	Reduce request frequency
403	UNAUTHORIZED	API unauthorized	Contact PayBy
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy
500	SYSTEM_ERROR	System error	Contact PayBy, retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk control verification failed	Please adjust business
62002	ORDER_FAILURE	Failed order initiated cancellation again. Failed order initiated refund.	Adjust merchant order number
62004	MERCHANT_ORDER_NO_NOT_EXIST	Order with merchant order number does not exist	Adjust merchant order number
62016	MERCHANT_ORDER_NO_EXIST	Same order number, different business parameter order creation request	Adjust order number
62026	PRODUCT_IS_NOT_APPLIED	Product not applied	Please apply for product
62028	ORDER_SUCCESS	Order already successful	Adjust merchant order number
62029	ORDER_CREATED	Order already created	Adjust merchant order number